<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
(C) Copyright MarketLive. 2006. All rights reserved.
MarketLive is a trademark of MarketLive, Inc.
Warning: This computer program is protected by copyright law and international treaties.
Unauthorized reproduction or distribution of this program, or any portion of it, may result
in severe civil and criminal penalties, and will be prosecuted to the maximum extent
possible under the law.
-->
</head>
<body bgcolor="white">
Defines the central entity APIs.
Defines the interfaces and behaviors that implementations of the
Entity-Home-Primary key pattern must adhere to.
Most types of "business data" are modelled using this pattern.

<h3>Determining Whether To Use This Pattern For a Particular Type of Data</h3>
<p/>
Use this pattern to model data that meet the following criteria:
<ul>
<li>
Each element of the data is uniquely identifiable through some kind of unique key.
</li>
<li>
Elements of the data have a lifespan longer than a single process.
</li>
</ul>
<h3>Key Responsibilities and Relationships of The Pattern</h3>
<p/>
The Entity-Home-Primary Key pattern defines three essential
roles, each characterized by an interface.
<p/>
The entity role is defined by the <code>IEntity</code> interface.
It represents a single element of a particular type
of data.  It generally corresponds to a "real world" object such as a product,
a person, or an order.
<p/>
The home role is defined by the <code>IEntityHome</code> interface.  It is used to control
the life-cycle of the entity.  Client code uses the Home object to create new
entities, to get references to existing entities, and to update or delete them.  The
home object is a special-purpose factory for the entity.  Entities should not be
instantiated directly; references should always be obtained from the home object.
<p/>
The primary key role is defined by the <code>IPrimaryKey</code> interface.  It acts as a unique
identifier for a an entity.  Each entity has exactly one primary key, and if two
instances of an entity have the same primary key, then the entities represent the
same "real world" object.  Primary keys are also instantiated by the home object.
Primary keys can always be written to and read as strings to enable the storage
and lookup of the corresponding entity across processes.  For example, on a B2C
site the primary key of a product is often written to the HTML form as a string.
When the form is posted back to the server, the primary key can be recovered from
the String and a reference to the corresponding product retrieved.

<h2>Additional Entity Features</h2>
The interfaces also provide for the exposure of the following functionality:
<ul>
<li>Change notification</li>
<li>Attribute pages</li>
<li>Entity, page, and attribute metadata</li>
</ul>
<h2>Guidelines for Implementing Entities</h2>
The <code>IEntity</code> and <code>IEntityHome</code> interfaces are intended to be
implemented for each type of entity.  Each entity is placed in a sub-package with
the package name matching the entity name (in all lower-case).
<p/>

<!-- Put @see and @since tags down here. -->

</body>
</html>
